DeepWiki

03.b - GitHub-App-Installation-Flow

Relevant source files

This document describes the GitHub App installation process that occurs after payment completion. It covers the user-facing installation interface, repository selection options, permission requests, and the technical mechanisms that capture the installation_id for downstream processing.

For the OAuth initiation that triggers this flow, see GitHub OAuth Initiation. For handling the OAuth callback after installation, see OAuth Callback Handler.

The GitHub App installation is a two-phase process that bridges payment completion to repository access provisioning. Unlike standard OAuth flows, GitHub Apps require users to explicitly install the app on their account and select which repositories to grant access to before OAuth authorization begins.

Sources: app/success/page.tsx L54-L59

README.md L246-L263

app/api/auth/github/setup/route.ts L4-L67

Success Page Installation PromptLink copied!

After completing Stripe payment, users land on /success with a session_id query parameter. This page serves as the gateway to GitHub App installation, with critical messaging about repository selection.

Success Page Component Structure

ElementPurposeImplementation
Video Tutorial15-second visual guideHosted at cdn.vibecoders.school
Warning BannerEmphasizes "Only select repositories"Amber-styled alert box
Connect ButtonInitiates GitHub App flowLinks to /api/auth/github?session_id=xxx
Session PersistenceCarries payment contextsession_id URL parameter

The success page implements a crucial educational step, displaying an auto-playing video that demonstrates the installation process visually. This reduces user error during repository selection.

Sources: app/success/page.tsx L10-L71

Sources: app/success/page.tsx L38-L53

The GitHub App installation UI presents users with two mutually exclusive options for repository access. This choice is user-controlled, not app-controlled, and has significant security implications.

OptionScopeRisk LevelRecommendation
All repositoriesCurrent + future reposHigh❌ Not recommended
Only select repositoriesUser-specified listLow✅ Recommended

The system architecture emphasizes repository selection restriction for three reasons:

  1. Minimal Access Principle: Users only need to grant access to the repository they want documented
  2. Future Repository Protection: "All repositories" includes repositories created after installation
  3. Blast Radius Limitation: If credentials are compromised, only selected repositories are exposed

The warning messaging appears in three locations:

Sources: app/success/page.tsx L38-L40

github-app-description.md L1-L46

README.md L142-L145

The GitHub App requests minimal read-only permissions to fulfill its repository access provisioning purpose:

Sources: README.md L130-L135

PermissionPurposeUsed In
Contents: ReadClone repository files for documentationAutomation scripts
Metadata: ReadRetrieve repository name, owner, visibilityAPI calls
Email addresses: ReadIdentify customer for repository namingRepository creation
read:userFetch GitHub usernameOAuth callback
user:emailRetrieve user email addressCustomer correlation

Note that all permissions are read-only. The app never requests write access to repositories, ensuring it cannot modify customer code.

Sources: README.md L128-L136

app/api/auth/github/setup/route.ts L59

When users click "Connect GitHub" on the success page, they are redirected to a GitHub-hosted installation interface. The URL follows this pattern:

https://github.com/apps/{GITHUB_APP_SLUG}/installations/new?state={state_token}

The GITHUB_APP_SLUG environment variable determines which GitHub App to install. For production, this is godeepwiki-github-integration.

Sources: app/success/page.tsx L54

When a user completes app installation, GitHub generates a unique installation_id that represents the relationship between the user's account and the installed app. This ID is permanent and survives across reinstallations unless the user explicitly uninstalls the app.

Sources: app/api/auth/github/setup/route.ts L4-L67

The /api/auth/github/setup route serves as an intermediary between GitHub App installation and OAuth authorization. This route captures the installation_id and bridges the two-phase authentication process.

// /api/auth/github/setup/route.tsexport async function GET(request: NextRequest)

The handler performs these operations in sequence:

  1. Extract Parameters app/api/auth/github/setup/route.ts L5-L10 * installation_id: The newly created installation identifier * setup_action: Either 'install' or 'update' * state: Optional state token for CSRF protection
  2. Validate Installation ID app/api/auth/github/setup/route.ts L13-L18 * Returns 400 error if installation_id is missing * This prevents the flow from continuing without proper installation
  3. Store Installation ID in Cookie app/api/auth/github/setup/route.ts L21-L28 * Cookie name: github_installation_id * Attributes: httpOnly, sameSite: 'lax', maxAge: 600 (10 minutes) * The cookie persists the installation ID for the OAuth callback handler
  4. Preserve State Token app/api/auth/github/setup/route.ts L31-L39 * If GitHub provided a state token, store it in github_oauth_state cookie * Otherwise, generate a new state token using crypto.randomUUID()
  5. Construct OAuth URL app/api/auth/github/setup/route.ts L54-L62 * Builds authorization URL with client_id, redirect_uri, state, and scope * Redirects user to GitHub OAuth authorization screen

Sources: app/api/auth/github/setup/route.ts L1-L67

The 10-minute expiration window is sufficient for the OAuth flow while minimizing the risk of cookie hijacking. The httpOnly flag prevents client-side JavaScript from accessing these security-sensitive cookies.

Sources: app/api/auth/github/setup/route.ts L22-L38

GitHub sends a setup_action parameter indicating the installation context:

ValueMeaningOccurrence
installFirst-time installationUser installs app for the first time
updatePermission or repository updateUser modifies existing installation

The system logs this action app/api/auth/github/setup/route.ts L64

but treats both cases identically in the flow. Both result in storing the installation_id and redirecting to OAuth.

Sources: app/api/auth/github/setup/route.ts L9-L64

The state token serves as CSRF protection during the OAuth flow. The setup handler either preserves GitHub's state or generates a new one:

const oauthState = state || crypto.randomUUID();

This state is stored in a cookie and verified in the OAuth callback handler to ensure the authorization response matches the original request.

Sources: app/api/auth/github/setup/route.ts L52

app/api/auth/github/setup/route.ts L32-L38

All authentication cookies use these security attributes:

AttributeValuePurpose
httpOnlytruePrevents XSS attacks
securetrue (production only)Enforces HTTPS in production
sameSite'lax'Prevents CSRF while allowing redirects
maxAge600 seconds10-minute expiration window
path'/'Available to all routes

The secure flag is conditionally applied based on NODE_ENV to support local development over HTTP.

Sources: app/api/auth/github/setup/route.ts L23-L27

app/api/auth/github/setup/route.ts L33-L37

The emphasis on "Only select repositories" throughout the UI is a defense-in-depth strategy:

  1. User Education: Video tutorial + warning banner on success page
  2. Documentation: GitHub App description field includes explicit warning
  3. README: Installation guide recommends specific repository selection

Even if the app's permissions are read-only, limiting the number of accessible repositories reduces the attack surface if the system is compromised.

Sources: app/success/page.tsx L38-L52

github-app-description.md L9-L11

README.md L143-L144

The setup callback handler bridges the gap between app installation and OAuth authorization. The installation_id stored in cookies during this phase is critical for the OAuth callback handler, which retrieves it to link payment (via session_id) to repository access (via installation_id).

The flow continues in the OAuth callback handler, documented in OAuth Callback Handler, which:

  • Retrieves the installation_id from the cookie
  • Exchanges the OAuth code for an access token
  • Logs the correlation between session_id and installation_id
  • Sends notifications to trigger automation

Sources: app/api/auth/github/setup/route.ts L21-L28

If the setup callback receives a request without an installation_id parameter, it returns:

{ "error": "Missing installation_id parameter" }

This typically indicates that the user cancelled the installation or that the GitHub App configuration is incorrect.

Sources: app/api/auth/github/setup/route.ts L14-L18

If GITHUB_CLIENT_ID is missing from environment variables, the setup handler returns:

{ "error": "GitHub client ID not configured" }

This prevents the OAuth redirect from constructing an invalid authorization URL.

Sources: app/api/auth/github/setup/route.ts L43-L49

The setup handler logs installation completion:

console.log(`[GitHub Setup] Installation ${installationId} completed (${setupAction}), redirecting to OAuth...`);

This log entry appears in Vercel logs and helps correlate installation attempts with subsequent OAuth callbacks.

Sources: app/api/auth/github/setup/route.ts L64

Refresh this wiki

Last indexed: 23 November 2025 (922b35)

On this page

Ask Devin about godeep.wiki-jb

03.b - GitHub-App-Installation-Flow | DeepWiki | godeep.wiki